The basic unit form creates or modifies a unit.
Form: unit id [ type ] properties...
This form defines a unit.
If a numeric id is supplied and matches the id of an existing unit,
then that unit will be modified by properties,
and the optional type will be interpreted as a new type for the unit.
Otherwise a new unit will be created,
with either id as its id or
a arbitrarily-selected one if id is already in use.
If the unit's id is newly-generated and no type has been specified,
then type #0 (first-defined type) will be the type of the unit.
An id of 0 can never match an existing unit id, so effect
will be as if it had been omitted.
Form: unit-type-name x y [ side-id ] properties...
This is an abbreviated form, in which
the x,y position is required, and an optional side id may be included.
The side id will come from unit-defaults if not specified.
The unit-type-name may be any valid unit type name or
defined name.
This form always results in a new unit.
Since there may be many units whose properties are similar, there is a "default unit" whose properties fill in missing properties in individual unit declarations.
Form: unit-defaults [ modifier ] properties...
This form sets the default values for all subsequent units read in,
in this and every other module not yet loaded.
The set of defaults is additive,
so for instance you can repeatedly change the default side of units.
If the symbol reset has been supplied for the optional modifier,
then all the defaults will be changed to the basic default
values, as described in this manual.
Symbol: reset
This is the symbol used to reset unit defaults; see above.
GlobalVariable: create-units-from-specs t/f
When true, unit forms actually cause units to be created. When false,
the unit forms are saved away and can be used later by a unit form
to supply values for properties.
Defaults to true.
This section lists properties of individual units. In general, they default to the most common or reasonable values, so need not always be specified, even in a saved game.
UnitProperty: @ x y [ z ]
This property is the position of the unit.
Defaults to -1,-1,0, which causes the unit to be placed randomly.
The optional altitude z can also be set separately with
the property z below.
If z is even and the unit is in the open,
then the unit's altitude is z/2;
if z is odd, then (z-1)/2 is the type of connection terrain
that the unit is on.
UnitProperty: z z
This property is identical to the optional z part of the @ property.
UnitProperty: s side
This property is the side of the unit.
It can be either a side name/noun/adjective (string) or id (number).
A value of 0 or "independent"
means that the unit is independent.
UnitProperty: os side
This property is the original side of the unit.
It can be either a side name/noun/adjective (string) or id (number).
A value of 0 or "independent"
means that the unit is/was originally independent.
Defaults to the unit's actual side when first read in or created.
UnitProperty: # n
This property is the unique numeric id of the unit. Defaults to a game-selected value.
UnitProperty: n str
This property is the name of the unit.
UnitProperty: nb n
This property is the number of the unit,
which starts at 1 and goes up.
Defaults to 0, which means that the unit is unnumbered.
UnitProperty: cp n
This property is the current completeness of the unit.
If negative, indicates that the unit will appear at a time
and place specified by the appear x-property.
Defaults to the cp-max for the type.
UnitProperty: hp n
This property is the current hit points of the unit.
Will be restricted to the range [0, hp-max].
An hp of 0 means that the unit is dead and will not appear in the game.
Defaults to hp-max for the unit's type.
UnitProperty: cxp cxp
This property is the combat experience of the unit. Experience starts at 0 for new units and goes up with each engagement in combat.
UnitProperty: mo n
This property is the morale of the unit.
Morale ranges from 0 to a maximum set by morale-max.
UnitProperty: trk n
This property is a bit vector indicating the sides that are currently tracking the unit's movements. The unit's own side is not included.
UnitProperty: m mtype-value-list
This property is the amounts of supplies being carried by the unit.
Defaults to 0 for each material type.
UnitProperty: tp utype-value-list
This property is the level of tooling to build each type of unit.
Defaults to 0 for each unit type.
UnitProperty: in x
This property is the id, name, or symbol of the unit's transport.
Defaults to 0, meaning that unit is not in any transport.
UnitProperty: opinions side-value-list...
This property is the unit's true feelings towards each side,
including its own side.
Defaults to 0 for each side.
UnitProperty: appear n
This property is the turn on which a unit will appear.
The unit's cp must also be negative, and its position must be
negatives of its position.
Defaults to -1.
UnitProperty: disappear n
This property is the turn on which a unit will disappear from
the game. Occupants will be ejected if possible; otherwise
they will disappear also.
Defaults to -1.
UnitProperty: sym symbol
This property is a symbol that is unique to this unit.
This symbol may appear instead of a unit id, for instance
as the value of the property in.
Defaults to ().
UnitProperty: x obj
This property is the optional extension properties of the unit.
Its value may be any object.
Defaults to ().
UnitExtensionProperty: sides list
This extension property is a list of side names that the unit may
be given to during setup. (See side property units.)
Defaults to ().
UnitProperty: acp n
This property is the number of action points left to the unit for this turn.
UnitProperty: acp0 n
This property is the initial number of action points for this turn, computed at the beginning of the turn.
UnitProperty: am n
This property is the actual number of moves (cell entries) executed so far in the current turn.
UnitProperty: a action
This property is the next action that the unit will perform.
UnitProperty: plan type [ creation-turn ] properties...
This property describes the unit's current plan.
PlanType: none
A unit with this type of plan does nothing. It is used when a side has no player.
PlanType: passive
This plan type is for units on a side that is being run directly by the side.
PlanType: defensive
This plan type is for units that defend areas or other units.
PlanType: offensive
This plan type is for units that are to be aggressive.
PlanType: exploratory
This plan type is for units that explore the world.
PlanType: random
A unit with this plan type will act randomly.
PlanProperty: goal goal
This property is the main goal of a unit's plan.
Defaults to ().
PlanProperty: formation goal
This property is the formation goal of a unit's plan.
If defined, it is a position goal that the unit should
try to achieve when it is not trying to achieve the main goal.
Defaults to ().
PlanProperty: tasks tasks...
This property is the complete task agenda for the unit's plan.
It is a list of tasks.
Defaults to ().
PlanProperty: asleep t/f
This property is true if the unit is asleep.
Defaults to false.
PlanProperty: reserve t/f
This property is true if the unit is in reserve.
Defaults to false.
PlanProperty: delayed t/f
This property is true if the unit's activity
has been delayed until all others have acted.
Defaults to false.
PlanProperty: wait t/f
This property is true if the unit is waiting for orders.
Defaults to false.
PlanProperty: ai-control t/f
This property is true if the unit can be controlled by
any AI associated with the side.
Defaults to true.
PlanProperty: supply-alarm t/f
This property is true if the unit should react when supply
is low.
Defaults to false.
PlanProperty: supply-is-low t/f
This property is true if the unit considers its supply
to be low.
Defaults to false.
PlanProperty: wait-transport t/f
This property is true if the unit is waiting for transport.
Defaults to false.
PlanProperty: initial-turn turn
This property is the turn upon which a plan should go into effect.
PlanProperty: final-turn turn
This property is the turn upon which a plan should be removed.
If the value is 0, then the plan is not scheduled to
be removed.
The possible types of goals are these:
GoalType: no-goal
GoalType: won-game
GoalType: lost-game
GoalType: world-is-known
GoalType: vicinity-is-known
GoalType: positions-known
GoalType: cell-is-occupied
GoalType: vicinity-is-held
GoalType: has-unit-type
GoalType: has-unit-type-near
GoalType: has-material-type
GoalType: keep-formation
This section lists all the types of tasks that a unit may perform. Every task includes the two parameters ex and re; the first is a record of how many times the task has been executed, and the second records how many times the task has failed. (Xconq will retry a failed task several times before abandoning it.)
TaskType: build ex re u n n2 unit-id
This type of task directs the unit to build n units of type u. n2 is the number already built in the run and unit-id is the (optional) id of a unit already being built.
TaskType: capture ex re unit-id
TaskType: disband ex re
This type of task directs the unit to disband itself.
TaskType: do-action ex re n action
TaskType: hit-position ex re x y z
This type of task directs the unit to attack or fire on any unfriendly units at the given location.
TaskType: hit-unit ex re unit-id
TaskType: move-dir ex re dir n
This type of task directs the unit to move in direction dir for a distance of n cells.
TaskType: move-to ex re x y z dist
This type of task directs the unit to move to a distance of no more than dist cells from the given location.
TaskType: occupy ex re unit-id
This type of task directs the unit to attempt to enter the given unit-id, moving adjacent to it first if necessary.
TaskType: pickup ex re unit-id
This type of task directs the unit to move towards the given unit-id.
TaskType: repair ex re unit-id
TaskType: resupply ex re
This type of task directs the unit to replenish its supplies, whether by doing more production or by moving to another unit that has supplies available.
TaskType: sentry ex re n
This task type directs the unit to stay where it is for the next n turns.